A-v5版本升级到v6.0.6.9版本

以下提到的所有 XAPP SDK 均指v6版本的 XAPP SDK，所有的更新内容都是相对于v5版本而言的，部分更新特性或者功能可能在最新版本的v5 XAPP SDK 中已经存在。

  • 版本更新
  1. 更新部分设备管理功能,内部逻辑调整与优化
  2. 优化与设备通讯处理
  3. 新增多点登录功能
  4. 新增 CM 连接/REST 接口对自签证书的支持
  5. 新增设备唯一标识

一、升级准备

从v5升级到v6需要进行一些升级准备，其中包括 XAPP SDK JAR 包的更新与一些配置工作。

温馨提示：由于每个项目的环境都存在一定的差异性，以下升级无法100%保证升级过程无障碍，请对当前项目进行备份后独立进行升级处理，以免造成不必要的操作问题

二、更新 XAPP SDK JAR 包

请参考快速开始-SDK导入及环境配置正确导入 XAPP SDK JAR 包。

升级时请注意以下事项：

  • 务必删除掉原有所有v5版本的依赖包后重新导入
  • 新 jar 包与旧 jar 包存在一些同名文件，务必注意不能错误引用
  • v6版本后，不再存在xlink_core_sdk.jar文件，请务必删除该文件

三、功能说明

3.1、新增

3.1.1、增加多点登录的支持

实现该功能需要 XLinkConfig 中新增的 resource 属性，这个属性意为登录源，用户可以在登录时指定登录源，不同登录源可同时登录，登陆源只支持数字和字母（暂不支持空格），最大长度为16个字符，默认为 null。

XLinkConfig config = XLinkConfig.newBuilder()
    //设置登录源,单点登录时可以不进行设置,不同登录源允许多点登录
    .setAuthResource(resource)
    ...
    .build();
XLinkAndroidSDK.init(config);

3.1.2、增加 CM 连接/ REST 对自签证书的 SSL 支持

部分情况下可能需要使用到企业的自签证书，此时默认的 SSL 处理将不能正常提供有效的校验及数据通行处理，新增了可自定义提供 CM 连接时的 SSL socket 对象

XLinkConfig config = XLinkConfig.newBuilder()
    //设置登录源,单点登录时可以不进行设置,不同登录源允许多点登录
    .setAuthResource(resource)
    ...
    .build();
XLinkAndroidSDK.init(config);

REST 接口是使用 retrofit 进行网络请求，部分 API 请求可能也需要进行 SSL 的证书配置，需要通过 okHttpClient 的配置。

对于原有的 REST 接口并不存在相关的 SSL 配置处理请求，所以新版本也提供了 REST 接口对 client 进行自定义配置的接口。

builder.setNetworkClientProcessor(new NetworkClientProcessor() {
    @Override
    public void processorClient(OkHttpClient.Builder builder) {
        //根据需要使用可自定义对 client 进行配置
        builder.sslSocketFactory(factory,manager);
    }
});

3.1.3、新增设备的唯一标志

旧的 XDevice 通常是通过 MAC 地址进行识别，在相对极端的情况下可能会导致识别出错的问题(如不同产品下允许有相同的 MAC 设备，尽管在实际场景中极少可能存在这种情况），所以 XDevice 将提供新的唯一标识用到标记当前的设备。

该值必然是非空字符串，至于其有效性要取决于 XDevice 对象中的数据（由 MAC 与 PID 决定），建议尽量使用此标识进行设备识别，使用 MAC 地址识别依然是可以的，但是可能存在一定的风险。

//设备的唯一标识由MAC与PID决定,当仅知道设备的MAC与PID时,可以通过以下方式获取到唯一标识
String devTag = DeviceHelper.generateDeviceTag(mac,pid);

3.2、移除

3.2.1、移除部分内部使用的任务，及部分废弃了部分类或者接口的回调方法

其它被废弃同时有其它替换 API 的方法请查看其它API变更

废弃的方法/类 原由 是否依然可用
XLinkLocalConnectionTask 不再使用内部连接任务管理本地状态 否
XLinkDeviceManager#getDeviceFromMacAddress() 不再使用 MAC 作为设备标识,不推荐使用 是
XLinkDeviceManager#getLocalConnectionTask() 不再使用内部连接任务管理本地状态 否
XLinkSDK.getDeviceList() 由于安全性考虑不推荐使用 否
XDevice#setLocalConnectionState() 不再支持内网连接状态的更新,连接状态由内部维护不能被外部更新 否
XDevice#setCloudConnectionState() 不再支持云端连接状态的更新,连接状态由内部维护不能被外部更新 否
XDevice#toJson() toJson允许导出有效的数据 是
XDevice#fromJson() fromJson暂时无法有效地将数据转成 XDevice 对象 否
XLinkConnectDeviceTask 不再支持此任务进行连接操作(暂时性,之后会使用其它的任务代替) 否

3.2.2、移除了后台保活服务及部分依赖库

//设备的唯一标识由MAC与PID决定,当仅知道设备的MAC与PID时,可以通过以下方式获取到唯一标识
String devTag = DeviceHelper.generateDeviceTag(mac,pid);
//不再需要在 gradle 中添加此依赖
compile 'com.legendmohe.maven:hellodaemon:1.1.5'
 
 
//不再需要此依赖库,已集成到SDK中并调整修复了一些问题
compile 'org.eclipse.paho:org.eclipse.paho.client.mqttv3:1.1.1'

注意：请务必取消其依赖，否则无法正常使用

3.2.3、移除旧的jar文件

新版XAPP SDK已经将 xlink_core_sdk.jar 与 xlink_sdk.jar 合并为一起，不再需要依赖旧的 xlink_core_sdk.jar，请务必确认一下所有的lib只需要压缩文件中的lib即可。

所有 libs 的文件列表如下（请确保依赖的 jar 包仅有以下的文件）：

  • xlink_sdk.jar
  • xlink_common.jar
  • xlink_task_lib.jar
  • xlink_wrapper.jar
  • xlink_restful.jar
  • expiringmap-0.5.7.jar（此 jar 是新增的）

3.3、变更

3.3.1、变更调试日志配置

新版本 XAPP SDK 对 LOG 配置进行了更新，允许设置 LOG 的一些基本配置从而更自主控制 LOG 输出。最主要的体现为：允许自定义 LOG 的输出路径

  • XAPP SDK 提供了默认的日志配置，包含以下设置：
    1. 日志输出等级设置为DEBUG
    2. 日志自动输出保存到文件中
    3. 日志输出路径为/sdcard/xlink/
    4. 日志文件名将以包名+时间为标识
new XLinkConfig.Builder()
    .setLogConfig(XLinkAndroidSDK.defaultLogConfig(this))
    ...

注意:必须设置LogConfig,否则无法正常输出日志

  • 自定义日志保存位置

通过创建的默认 config 可以修改调试日志输出路径。

//更新日志输出路径
BaseLog.Config logConfig=XLinkAndroidSDK.defaultLogConfig(this)
    .setLogoutPath("/xxx/xxx");
     
//设置日志config
new XLinkConfig.Builder()
    .setLogConfig(logConfig)
    ...

若默认配置无法满足需求,更多详情说明请参考进阶篇-SDK高级配置

3.3.2、变更崩溃日志收集

新版本的崩溃日志与旧版本的崩溃日志收集功能是一致的，类似于日志配置更改，也允许对崩溃日志的保存位置进行修改。

新版本中开启崩溃日志收集时，要求必须提供崩溃信息收集对象用于崩溃环境的信息收集并保存到文件中。

  • 默认配置

默认日志输出路径为/sdcard/xlink/crash

new XLinkConfig.Builder()
    //开启崩溃日志收集
    .setAutoDumpCrash(true)
    //设置默认的崩溃信息收集对象
    .setCrashInfoProviderable(new XLinkCrashInfoProvider(this))
    ...

注意：当开启崩溃日志收集时，必须设置崩溃信息收集对象，否则无法正常初始化 XAPP SDK （运行时会抛出异常）

  • 自定义崩溃日志文件保存位置

XLinkCrashInfoProvider提供了三个构造方法用于不同的路径配置，默认情况下会收集当前移动设备的一些基本信息（包括Android版本与机型等）

//默认使用sdcard,存储子路径为/xlink/crash
new XLinkCrashInfoProvider(context);
//默认使用sdcard,存储子路径为/package
new XLinkCrashInfoProvider(context,"/package");
//由绝对存储路径决定存储位置
new XLinkCrashInfoProvider(context.getPackageName(),"/absolutely_path");

若默认配置无法满足需求,更多详情说明请参考进阶篇-SDK高级配置

3.3.3、变更初始化方式

旧版本 XAPP SDK 的初始化需要传入ApplicationContext进行一些环境相关的处理，新版本的 XAPP SDK 不再依赖于Context，而且在调试日志或崩溃日志中也不会对该Context进行保存，仅仅是使用初始化时的包名并生成日志路径。

//唯一初始化入口
XLinkAndroidSDK.init(builder.build());

注意:必须使用此方法进行初始化,因为在初始化时对线程和数据进行了一些转接处理

XLinkAndroidSDK同时还提供了start()与stop()的方法，但是直接使用原XLinkSDK.start()与XLinkSDK.stop()的方法也是允许的。

3.3.4、变更错误码

错误码是本次版本升级更新的重点之一，由于旧版本的错误以枚举常量的形式存在，同时错误码所能表达的信息非常有限（主要体现在错误码无法直接指明具体表明错误原因），所以针对此问题对错误码系统进行了调整更新。新旧版本的错误码主要差异如下：

- 类型 使用方式 关联类
旧错误码 Enum XLinkErrorCode.xxx,直接以枚举表示当前错误码的意义 无
新错误码 int XLinkErrorCodes.xxx,直接以整数表示当前错误码的意义 XLinkErrorDesc，错误码描述信息 XLinkErrorCodeHelper，错误码辅助类 XLinkCoreException，错误码的异常信息容器

错误码列表请参考APP-SDK错误码

从接口中获取到返回的错误码之后，可能需要一些错误码的信息，如错误码的名称、错误码表示的意义等。错误码相关的信息会存储到固定的类 XLinkErrorDesc 中，携带了错误码的名称与信息。

public final class XLinkErrorDesc {
    //错误码名称（英文说明）
    public final String mErrorName;
    //错误码描述（中文说明）
    public final String mErrorDesc;
}

任何时候，已知一个错误码值时，可以通过错误码辅助工具获取到对应的错误码信息。

//获取错误码信息
XLinkErrorDesc desc=XLinkErrorCodeHelper.getErrorCodeDesc(400101);
//获取错误码名称
String codeName=XLinkErrorCodeHelper.getErrorCodeName(400101);
String codeName=desc.mErrorName;
//获取错误码描述信息(中文说明)
String codeDesc=XLinkErrorCodeHelper.getErrorCodeDesc(400101);
String codeDesc=desc.mErrorDesc;
 
//示例以上错误码输出为: name=ERROR_UNKNOWN, desc=未知错误

3.3.5、变更任务回调参数

由于错误码的变更，旧版本的任务回调参数与新版本的回调参数发生变更，其变更主要在错误码类型与使用上。

  • 旧版本的任务回调
new XLinkTaskListener{
    //各种TaskListener的错误回调，错误码类型为枚举
    public void onError(XLinkErrorCode errorCode){
        switch (errorCode) {
            //各种错误判断分支处理
            case xxx:
            break;
        }
    }
}
  • 新版本的任务回调

新的回调将直接提供当前出错时的异常信息，同时请注意不管是旧的接口还是新的回调接口，参数类型都已经更新为 XLinkCoreException，是一个具体的异常信息，不再是一个枚举的错误码了。

new XLinkTaskListener{
    //各种TaskListener的错误回调，直接返回异常信息
    //错误码与错误信息包含在异常信息中
    public void onError(XLinkCoreException ex){
        //获取错误码，注意参数类型为整数 int
        int errorCode =  ex.getErrorCode();
        //获取错误码名称及说明
        XLinkErrorDesc desc =  ex.getErrorDesc();
        //错误码名称（英文）
        String errorName = desc.mErrorName;
        //错误码说明（中文）
        String errorDesc = desc.mErrorDesc;
         
        //获取原始的异常信息,注意不一定每个异常信息都会有
        Throwable src=xLinkErrorCode.getSrcThrowable();
         
         
        //快捷获取错误码名称
        String errorName = desc.getErrorName();
        //快捷获取错误码说明
        String errorDesc = desc.getErrorDesc();
    }
}

3.3.6、错误码快捷更新操作

3.3.6.1、全局批量更新

请严格按以下流程进行批量操作，该批量操作是为了将废弃错误码使用与最新的错误码快速替换达到兼容的目的，以下指全局查找并替换。

请注意：在如果同时使用到RESTFUL接口，可能存在不同包名下的 XLinkErrorCode（一般情况下不会使用到），此时全局替换可能会小部分被误操作，如果存在多个 module 可以选择 module 进行指定 module 处理，防止影响到其它不相关 module

搜索 替换 备注
XLinkErrorCode XLinkCoreException 注意选择大小写敏感与全单词匹配进行替换
.name() .getErrorName() (原枚举类型的名称)注意选择大小写敏感
cn.xlink.sdk.v5.module.main.XLinkCoreException cn.xlink.sdk.core.XLinkCoreException 注意选择大小写敏感与全单词匹配进行替换
3.3.6.2、局部更新处理

通过以上批量变更，实际上已经处理了大部分的错误码，但是由于XLinkErrorCode的枚举已经被废弃并不再使用，所以所有枚举的比较都是无效的。对于原本进行处理的枚举常量（如switch中或者if中判断使用）请通过以下方式解决。

  • 以ERROR_API_开头的所有枚举常量，不需要进行任何更改，只需要将其引用类替换为XLinkErrorCodes即可
//原代码
XLinkErrorCode code = fromCode;
switch(code){
    case ERROR_API_ACCOUNT_VAILD_ERROR:
        break;
}
 
//更新代码
//所有错误码都是int类型
int code = fromCode.getErrorCode();
switch(code){
    //添加上XLinkErrorCodes类引用即可
    case XLinkErrorCodes.ERROR_API_ACCOUNT_VAILD_ERROR:
        break;
}

注意：所有 RESTFUL 接口操作的错误码都是ERROR_API_开头

  • 在原XLinkTaskListener中使用getThrowable()方法将不再支持，因为onError()参数即返回了异常信息，请直接使用返回的XLinkCoreException参数进行替换处理。
//原代码
public void onError(XLinkCoreException ex){
    showErrorMsg(getThrowable());
}
 
//更新代码
public void onError(XLinkCoreException ex){
    showErrorMsg(ex);
}
  • 旧错误码中可能会使用到枚举常量的属性方法如name()，由于已经更换成XLinkCoreException，需要使用进行一些替换工作
（枚举类中）旧方法 （异常类中）新方法 是否需要更新方法签名
XLinkErrorCode.name() XLinkCoreException.getErrorName() 是
XLinkErrorCode.getValue() XLinkCoreException.getErrorCode() 或XLinkCoreException.getValue() 可以不更新

3.3.7、变更接口

3.3.7.1、参数变更

部分任务的参数发生变更，删减了无效的方法，只保留有效的参数值

  • XLinkGetDataPointMetaInfoTask-获取数据端点模板

获取数据端点模板的参数实际上只需要产品 ID，不需要设备对象，所以参数变更为产品 ID，推荐进行修改

XLinkGetDataPointMetaInfoTask.newBuilder()
    .setProductId(xxx)
    //保留了旧的方法,依然可用,但是不推荐使用
    .setDevice(device)
    ...
  • XLinkShareDeviceTask-回调返回值变更

分享设备任务中，回调的返回值不再是String类型，而是DeviceApi.ShareDeviceResponse，原返回值为分享的邀请码，通过shareDeviceResponse.inviteCode即可获取该值(该对象中仅有此字段)

//旧方法参数类型为String
public void onComplete(String result){
    //获取邀请码,返回值本身就是邀请码
    String invitedCode = result;
}
 
//新方法参数类型为DeviceApi.ShareDeviceResponse
public void onComplete(DeviceApi.ShareDeviceResponse result){
    //获取邀请码,从返回对象中获取
    String invitedCode = result.inviteCode;
}
3.3.7.2、API 替换或变更

存在其它一部分 API 变更,请参考以下的变更

旧API 新API 功能是否变更 变更说明
XDevice#setActive() XDevice#setIsActive() 否 -
XLinkErrorCode#name() XLinkCoreException#getErrorName() 否 错误码变更
XLinkDeviceManager#getItem() XLinkDeviceManger#getDevice() 否 传递参数已变更,请注意
XLinkDeviceManager#removeItemByKey() XLinkDeviceManger#removeDeviceByDevTag() 否 传递参数已变更,请注意
XLinkDeviceManager#removeItemByKey() XLinkDeviceManager#removeDeviceByDevTag() 否 传递参数已变更,请注意
3.3.7.3、方法变更

由于数据结构进行了一些调整，有一部分方法不再支持或者被废弃不推荐使用(也可能是会影响到性能问题不再推荐使用)。

  • XLinkDeviceManager-获取设备对象方法变更

在设备管理对象中XLinkDeviceManager旧的获取设备对象的方法不再支持,需要使用新的方法获取设备对象,同时使用设备对象时使用新的唯一标识

//已废弃不再支持
XDevice oldDev = XLinkDeviceManager.getInstance().getItem(mac);
//已废弃,依然可用,但不推荐使用
XDevice oldDev = XLinkDeviceManager.getInstance().getDeviceFromMacAddress(mac);
 
//必须使用新的标识获取设备
XDevice newDev = XLinkDeviceManager.getInstance().getDevice(devTag);

注意：不再存在getItem()的方法获取设备对象，仅允许通过getDevice()方法获取设备对象，由于内容数据维护结构更新，所以废弃该方法是为了避免在应用中使用并未注意更新导致了一些不必要的错误。

3.3.7.4、变更数据端点值获取方式

数据端点中存在BOOL类型与BYTE类型的数据端点，在旧版本中二者是的类型是独立不同的，数据也无法互通。

但实际上二者缓存的数据是一致的，BOOL数据实际上存储时是使用一个 Byte 进行存储，所以在新版本中将两者的数据类型统一起来，仅仅是对提供了获取不同类型数据的方法，并允许两个类型的数据相互设置和保存。

byte byteValue=1;
//设置数据类型为bool
dataPoint.setType(DataPointValueType.BOOL);
//允许直接设置一个byte,0为false其它数值为1
dataPoint.setValue(byteValue);
//推荐对应类型设置相同类型的数据
dataPoint.setValue(false);
 
//设置数据类型为byte
dataPoint.setType(DataPointValueType.BYTE);
dataPoint.setValue(byteValue);
//允许直接使用boolean设置到类型为byte的数据,实际的数据值false=0,true=1
dataPoint.setValue(false);

对于数据获取时，由于 XAPP SDK 会尽可能保证数据模板的应用和使用，所以获取到XAPP SDK时会根据模板对数据类型进行更新（如模板中数据端点配置为BOOL时，实际的数据端点类型为BYTE时，将会将类型自动修正为BOOL）

推荐根据类型即可通过提供的方法对数据进行获取

byte byteValue=1;
//设置数据类型为bool
dataPoint.setType(DataPointValueType.BOOL);
//允许直接设置一个byte,0为false其它数值为1
dataPoint.setValue(byteValue);
//推荐对应类型设置相同类型的数据
dataPoint.setValue(false);
 
//设置数据类型为byte
dataPoint.setType(DataPointValueType.BYTE);
dataPoint.setValue(byteValue);
//允许直接使用boolean设置到类型为byte的数据,实际的数据值false=0,true=1
dataPoint.setValue(false);

获取数据值时每个类型都提供了两个方法，分别是带默认值的方法获取及可能抛出异常的方法获取。

//不抛出异常但需要提供默认值
dataPoint.getAsXXX(Type defaultValue)
//可能抛出异常,用于在不使用默认值需要明确知道当前值是否能转换成对应的数据时使用,转换失败时抛出异常
dataPoint.getAsXXX() throws Exception

任何情况下获取数据值都有可能抛出异常，因为数据值dataPoint.getValue()获取的值是Object类型，可能是任何类型(由类型决定)，当其类型无法与BTYE或者BOOL进行转换时(如String)则必然会抛出异常。

所以使用不抛出异常的方法时必须提供一个默认值，用以在无法正确转换并获取到数据时返回默认值

兼容处理：对于类型类型为BOOL的数据，考虑旧版本的接口兼容使用，当数据值有效时，调用默认方法dataPoint.getValue()将会自动进行数据类型转换为Boolean类型返回

同时提供了新的获取原始数据值的方法dataPoint.getRawValue()方便某些情况下只考虑使用原始数据

注意：推荐使用新的接口getAsXXX()获取对应类型的数据

详情说明请参考进阶篇-设备物模型详解

四、更新说明

日期 更新内容
2018.07.05 更新版本升级说明
没找到需要的文档？
你可以提交工单反馈 或 阅读常见问题
客服工单常见问题